/*
  protocol.h - controls Grbl execution protocol and procedures

  Part of grblHAL

  Copyright (c) 2016-2024 Terje Io
  Copyright (c) 2011-2016 Sungeun K. Jeon for Gnea Research LLC
  Copyright (c) 2009-2011 Simen Svale Skogsrud

  grblHAL is free software: you can redistribute it and/or modify
  it under the terms of the GNU General Public License as published by
  the Free Software Foundation, either version 3 of the License, or
  (at your option) any later version.

  grblHAL is distributed in the hope that it will be useful,
  but WITHOUT ANY WARRANTY; without even the implied warranty of
  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
  GNU General Public License for more details.

  You should have received a copy of the GNU General Public License
  along with grblHAL. If not, see <http://www.gnu.org/licenses/>.
*/

#ifndef _PROTOCOL_H_
#define _PROTOCOL_H_

#include "task.h"

// Line buffer size from the input stream to be executed.
// NOTE: Not a problem except for extreme cases, but the line buffer size can be too small
// and g-code blocks can get truncated. Officially, the g-code standards support up to 256
// characters. In future versions, this will be increased, when we know how much extra
// memory space we can invest into here or we re-write the g-code parser not to have this
// buffer.
#ifndef LINE_BUFFER_SIZE
  #define LINE_BUFFER_SIZE 257 // 256 characters plus terminator
#endif

/*
联合体的定义方式的好处
这种模式通常用于处理函数接口的兼容性问题。
例如，如果你在较早的实现中使用了 on_execute_realtime_ptr 类型，现在改用 foreground_task_ptr 类型，但希望现有代码不需要修改，可以用这种方式。
*/
typedef union {
    foreground_task_ptr fn;
    on_execute_realtime_ptr fn_deprecated;
} fg_task_ptr __attribute__ ((__transparent_union__));

// Starts grblHAL main loop. It handles all incoming characters from the input stream and executes
// them as they complete. It is also responsible for finishing the initialization procedures.
bool protocol_main_loop(void);

// Checks and executes a realtime command at various stop points in main program
bool protocol_execute_realtime (void);
bool protocol_exec_rt_system (void);
void protocol_execute_noop (uint_fast16_t state);
bool protocol_enqueue_rt_command (on_execute_realtime_ptr fn); // 本质上是调用 protocol_enqueue_foreground_task
bool protocol_enqueue_foreground_task (fg_task_ptr fn, void *data);// 注册函数到 realtime_queue 队列中,会通过 protocol_execute_rt_commands 调用 protocol_execute_rt_commands 最终执行注册进去的RT函数

// Executes the auto cycle feature, if enabled.
void protocol_auto_cycle_start (void);// 只知道它是设置了一个标志位,但是具体怎么起作用的还不知道

// Block until all buffered steps are executed
// 这个函数里面有个死循环;具备阻塞能力
bool protocol_buffer_synchronize (void);
// 处理长度为1个字节的RT指令
bool protocol_enqueue_realtime_command (char c);
bool protocol_enqueue_gcode (char *data);
void protocol_message (char *message);//这个是占位函数

#endif
